{!extends base.html !}
{!block title!}{%set page 'userguide'%}Jangod, end user manual{!endblock!}
{!block content!}
<h1>Syntax of template language</h1>
<p>About what's Jangod and what it does, see <a href="index.html" title="Jangod introduction" >here</a>. 
This document is for end users (may be a web designer) as a manual, it all 
about making templates. Quick link to build-in <a href="builtins.html#tag" title="tags manual">tags</a>, 
<a href="builtins.html#filter" title="filters manual">filters</a>, 
<a href="builtins.html#macro" title="macros manual">macros</a>.
</p>
<a name="template"></a><h2>Templates</h2>
<p>Any text file, no matter what suffix is having, can be a template. 
As when you insert a text file with some of Jangod <a href="#element">elements</a>, 
that is ready a Jangod template. Other text (which non-jangod elements) will be 
render as it's now(except some <a href="features.html#forgiveness">special characters</a>).
We use template to define the format of the final document is being generated, 
it carries common output fixed, and differences marked with Jangod element, 
which will be replaced with the text computed-out runtime by engine. 
Taking regular text (fixed, direct output) as regular elements, a Jangod template 
can be seen to be composed by a series of elements in order.
</p>
<a name="syntax"></a><h2>Syntax</h2>
<p>Jangod's syntax is simple, similar with Django template language, but easier to use. 
Here we just list the usage of built-in libraries, in most cases, these library items 
are enough for you. Of course, developers can add their own libraries or even change 
the usage of built-in libraries, creating own special syntax 
(see <a href="customize.html" title="customize engine">customization</a>). Therefore, 
if document doesn't match actual situation in use, there's no need wondering. 
Although the syntax can be ever-changing, it still follow some basic rules, which 
will be presented below.
</p>
<a name="concept"></a><h2>Basic concept</h2>
<p>Just saying that the syntax may vary, but the basic concepts are the same. 
Known these, you can just master Jangod and all its derivative language.
</p>
<a name="element"></a><h3>Four elements</h3>
<p>Elements constitutes the template. There are only 4 elements.</p>
<a name="echo-element"></a><h4>echo element</h4>
<p>An echo element is surrounded by '{\{' and '}}'. The character string in it 
is an <a href="#expression">expression</a>. Template engine will calculate the 
expression a result value according to runtime environment, then the value 
replace the whole element while rendering.
</p>
<a name="tag-element"></a><h4>tag element</h4>
<p>Tag used to control the logic of render flow, is surrounded by '{\%' and '%}'. 
A tag may contains body content, which consists of a number of regular text or elements. 
Tag with body needs an end tag as siege, tags without body do not need end tag.
Here is a if test tag :
<pre class="code">
{\% if post.comments %}
    comments ( {\{post.comments|length}} )
{\% else %}
    post a comment.
{\% endif %}
</pre>
</p>
<a name="comment-element"></a><h4>comment element</h4>
<p>It could be some text that you don't want them to appear in generated output, 
use comment element which surrounded by '{\#' and '#}'. Code in these elements produce 
none effect, will be ignored. Comment element can comment-out other elements, but 
a comment element must not be nested in another comment element, it will consider 
end in the time of first encountered '#}'.
<pre class="code">
{\#  You can't see me.
    No, i see you.  #}
</pre>
</p>
<a name="macro-element"></a><h4>macro element</h4>
<p>Macro defines a number of reusable components, which can contain regular text 
and jangod elements. After definition, we can repeatedly use them where in need.
Macro is aim to adjust elements sequence and entire composition of the template.
</p>
<a name="library"></a><h3>Three libraries</h3>
<p>Jangod elements may need to invoke objects to do some action, these object items 
are collected in libraries. Object items are divided into 3 libraries based on 
their purpose.
</p>
<a name="tag-library"></a><h4>tag library</h4>
<p>Each tag element must invoke an object item, and only one. These items are in 
tag library. Items have their own purpose and usage. Tag library is primarily used
to control the output render flow. For details see  
<a href="builtins.html#tag" title="tags manual">built-in tags</a>.
</p>
<a name="filter-library"></a><h4>filter library</h4>
<p>What's a filter? It's a pipe for data (<a href="#expression">expression</a>). 
Using filter to do certain algorithms on a data and get another value of data. 
The echo elements and tag elements can use filters. To invoke a filter is connecting
data(expression) and the filter with a character '|'. For example, 'var1|addAll:arg1,b2' 
means making the fitler 'addAll' on data 'var1', and the 'addAll' fitler needs 
two arguments 'arg1', 'b2'. The result we may get from this example is summary of
var1, arg1 and b2. Filter can have arguments partition by ':' , or no argument 
without ':'. Through successive invoke many filters, to achieve complex arithmetic.
For details see <a href="builtins.html#filter" title="filters manual">built-in filters</a>.
</p>
<a name="macro-library"></a><h4>macro library</h4>
<p>Similar to tag library, they are used in the macro elements differently. 
Macro library items are for refactoring template elements structure. 
For details see <a href="builtins.html#macro" title="macros manual">build-in macros</a>.
</p>
<a name="expression"></a><h3>expression</h3>
<p>From above we learn expression probably approximate to 
data. Expression is data and its arithmetic, evaluating new data. The simplest 
expression is a variable, such as 'post', 'post.id' and so. Complex expressions, 
such as 'posts|length', formed by a variable and filter. More complex expressions, 
such as "post.title|cut:'jinja'|length", composed by variable and multiple filters, 
or said, composed by expression and a filter. Constant expression, indicated by 
quotation marks, like "'post'", represent data for string "post" rather than the 
variable 'post'. 
<pre class="code">
a|or:b|not|and:c,d   {\# equals  !(a or b) and c and d  #}
{\% for view in viewList|reverse %}...{\%endfor%}  {\#  loop view list reverse  #}
</pre>
</p>
<a name="data-model"></a><h2>Data model</h2>
<p>Data model is the data container where template variables obtain value from. 
Most of template engines have the similar data model, it's accepted widely. 
<pre class="code">
(root)
  |
  +- views
  |   |
  |   +- (1)
  |   |   |
  |   |   +- name = "jangod"
  |   |   |
  |   |   +- theme = "default"
  |   |   |
  |   |   +- version = 0.5
  |   |
  |   +- (2)
  |   |   |
  |   |   +- name = "django"
  |   |   |
  |   |   +- <span class="light">theme</span> = "mvc"
  |   |   |
  |   |   +- version = 1.1
  |   |
  |   +- (3)
  |       |
  |       +- name = "java"
  |       |
  |       +- theme = "language"
  |       |
  |       +- version = 6
  |
  +- server
      |
      +- <span class="light">controls</span>
      |   |
      |   +- (1) = "engine"
      |   |
      |   +- (2) = "script"
      |
      +- models
          |
          +- <span class="light">key1</span> = HashMap
          |
          +- key2 = Cache 
</pre><br />
Here said model looks like above tree structure, doesn't mean it actually is 
stored data in this way, but simply that we can retrieve whatever data this 
way. The unification method to access is using dot '.' , no matter variable is
an object(<span class="light">server.controls</span>), a collection
(<span class="light">views.2.theme</span>), or a map
(<span class="light">server.models.key1</span>) etc.
As for the realization of the internal data model needs no concern, any Java 
class implements Map&lt;String, Object&gt; could be a data model. And you can
create own data model to satisfy your desire, such as lazy-load, just-in-time, 
cachable and so on.
</p>
<a name="inheritance"></a><h2>Template inheritance</h2>
<p>
The most powerful and useful function of Jangod is template inheritance. 
Template inheritance allows you to build a skeleton template framework that 
contains all the common elements of your document and defines sub-blocks that 
child templates can override them.<br />
It's about to divide your document into several sections which can be replaced
arbitrarily by tags or by macros. 
</p>
<a name="tag-inheritance"></a><h3>Inheritance with tags</h3>
<pre class="code">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;<span class="light">{\% block title %}</span>Jangod 模板引擎<span class="light">{\% endblock %}</span>&lt;/title&gt;
    &lt;link rel="stylesheet" href="style.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div id="content"&gt;
        <span class="light">{\% block content %}{\% endblock %}</span>
    &lt;/div&gt;
    &lt;div id="footer"&gt;
        <span class="light">{\% block footer %}</span>
        &copy; Copyright 2010
        <span class="light">{\% endblock %}</span>
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre><p>
This template, which we'll call "base.html", is a framework separating out three
blocks (named title, content, footer). Its child templates can rewrite these 
blocks as they need. One of its children can be like followed:
</p><pre class="code">
<span class="light">{\% extends "base.html" %}</span>
<span class="light">{\% block title %}</span>Hello {\{user.name}}<span class="light">{\% endblock %}</span>
<span class="light">{\% block content %}</span>
    &lt;h1&gt;Recencies&lt;/h1&gt;
    &lt;ul&gt;
        {\% for post in posts %}
            &lt;li&gt;{\{post.title}}&lt;/li&gt;
        {\% endfor %}
    &lt;/ul&gt;
<span class="light">{\% endblock %}</span>
</pre> 
<p>
The tag "<a href='builtins.html#extends-tag' title='tag extends description'>extends</a>" is 
the key. It tells the template engine that this template use a document framework.
Its extension framework is called parent template. When the template engine evaluates this 
template, it locates and renders the parent first. The tag "<a href='builtins.html#block-tag' 
title='tag block description'>block</a>" indicats sections to be overrided. The output might 
look like:
</p>
<pre class="code">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;Hello Django&lt;/title&gt;
    &lt;link rel="stylesheet" href="style.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div id="content"&gt;
            &lt;h1&gt;Recencies&lt;/h1&gt;
            &lt;ul&gt;
                &lt;li&gt;open source&lt;/li&gt;
                &lt;li&gt;spring mvc&lt;/li&gt;
                &lt;li&gt;模板语言&lt;/li&gt;
            &lt;/ul&gt;
    &lt;/div&gt;
    &lt;div id="footer"&gt;
        &copy; Copyright 2010
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<a name="macro-inheritance"></a><h3>Inheritance with macros</h3>
<p>
Macro template inheritance do same purpose as tag did. But it uses macro elements, 
and runs quickly. The parent template:
</p>
<pre class="code">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;<span class="light">{\! block title !}</span>Jangod 模板引擎<span class="light">{\! endblock !}</span>&lt;/title&gt;
    &lt;link rel="stylesheet" href="style.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div id="content"&gt;
        <span class="light">{\! block content !}{\! endblock !}</span>
    &lt;/div&gt;
    &lt;div id="footer"&gt;
        <span class="light">{\! block footer !}</span>
        &copy; Copyright 2010
        <span class="light">{\! endblock !}</span>
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>The child may likes: </p>
<pre class="code">
<span class="light">{\! extends "base.html" !}</span>
<span class="light">{\! block title !}</span>Hello {\{user.name}}<span class="light">{\! endblock !}</span>
<span class="light">{\! block content !}</span>
    &lt;h1&gt;Recencies&lt;/h1&gt;
    &lt;ul&gt;
        {\% for post in posts %}
            &lt;li&gt;{\{post.title}}&lt;/li&gt;
        {\% endfor %}
    &lt;/ul&gt;
<span class="light">{\! endblock !}</span>
</pre>
<p>
The first time when the template engine evaluates this template, it will produce a new 
template and cache it in memory, then use forever. The production template is:
</p>
<pre class="code">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;Hello {\{user.name}}&lt;/title&gt;
    &lt;link rel="stylesheet" href="style.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div id="content"&gt;
        &lt;h1&gt;Recencies&lt;/h1&gt;
        &lt;ul&gt;
            {\% for post in posts %}
                &lt;li&gt;{\{post.title}}&lt;/li&gt;
            {\% endfor %}
        &lt;/ul&gt;
    &lt;/div&gt;
    &lt;div id="footer"&gt;
        &copy; Copyright 2010
    &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>
Every child can have its production template cached. See about macro 
<a href="builtins.html#extends-macro" title="macro extends description">extends</a> and 
<a href="builtins.html#block-macro" title="macro block description">block</a>.
</p>
{!endblock!}

{!block table !}
<div class="sidebar fixed">
<h2>index</h2>
<ul>
<li><a href="#template">template</a></li>
<li><a href="#syntax">syntax</a></li>
<li><a href="#concept">concept</a>
	<ul>
		<li><a href="#element">elements</a>
			<ul>
				<li><a href="#echo-element">echo</a></li>
				<li><a href="#tag-element">tag</a></li>
				<li><a href="#comment-element">comment</a></li>
				<li><a href="#macro-element">macro</a></li>
			</ul>
		</li>
		<li><a href="#library">libraries</a>
			<ul>
				<li><a href="#tag-library">tags</a></li>
				<li><a href="#filter-library">filters</a></li>
				<li><a href="#macro-library">macros</a></li>
			</ul>
		</li>
		<li><a href="#expression">expression</a></li>
	</ul>
</li>
<li><a href="#data-model">data model</a></li>
<li><a href="#inheritance">inheritance</a>
	<ul>
		<li><a href="#tag-inheritance">tag inheritance</a></li>
		<li><a href="#macro-inheritance">macro inheritance</a></li>
	</ul>
</li>
</ul>
</div>
{!endblock!}